home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp95 / freyja13.exe / lha / XPRINTF.DOC < prev   
Text File  |  1992-03-22  |  5KB  |  144 lines
  1.          XPRINTF:  Extended version of PRINTF
  2.  
  3.                Craig A. Finseth
  4.                 25 August 1989
  5.  
  6.  
  7. OVERVIEW
  8.  
  9. The XPRINTF functions provide a versions of printf and sprintf with
  10. extended functionality.  Most printf functions are supported.
  11.  
  12.  
  13.  
  14. FUNCTIONS
  15.  
  16.     void xprintf(const char *format, ...)
  17.  
  18. Formats the arguments as specified by the format string (see below).
  19. All output is buffered (in 1024 byte chunks) and sent with one
  20. "write(1,...)" call.  Fputs was not used because the string may
  21. contain NULs.
  22.  
  23.     void xdprintf(const int fd, const char *format, ...)
  24.  
  25. As xprintf except the all output is sent to file descriptor FD.
  26.  
  27.     void xeprintf(const char *format, ...)
  28.  
  29. As xprintf except the all output is sent to standard error, file
  30. descriptor 2.
  31.  
  32.     void xsprintf(char *string, const char *format, ...)
  33.  
  34. As xprintf except that the formatted output is stored in the string
  35. STRING.  STRING is assumed to be long enough.  If the resulting string
  36. contains NULs, STRING will appear to be truncated.
  37.  
  38.  
  39.  
  40. THE FORMAT STRING
  41.  
  42. All characters except "%" print as themselves.  "%" introduces a
  43. format item.  "%%" prints as "%".  The general format is:
  44.  
  45.     %<digits><character>
  46.  
  47. The character specifies how the formatting should be done.  The digits
  48. form a number (the argument) which provides information about how to
  49. format.  Digits are not required.  If the digits are "*", the next
  50. argument is fetched and its value is used as the argument.  The
  51. upper/lower case of the formatting character is ignored.
  52.  
  53. Formatting characters:
  54.  
  55. Control
  56.  
  57. %[a%;b..%:z%]    Case/If statement.  The next argument is fetched.  If
  58.         it is zero, the first text (A) is formatted.  If the
  59.         next argument is one, text B is formatted.  Texts are
  60.         separated by "%;".  "%:" serves as an else clause.
  61.         Case/ifs do not nest.
  62.  
  63. %(a%)        Loop.  The next argument is fetched and the text is
  64.         repeated the specified number of times.  Loops do not
  65.         nest.
  66.  
  67. %r        Recursion.  The next two arguments are fetched.  The
  68.         first one indicates a format string to be interpreted
  69.         and the second one is a pointer to an array of
  70.         argument values.
  71.  
  72. Numbers
  73.  
  74. %#,        Format an int as a signed, decimal number with commas
  75.         every three digits.  # is the field width to use NOT
  76.         COUNTING THE COMMAS.  If the number is smaller than
  77.         the field width, it is right justified and space
  78.         filled.  If the number is larger than the field width,
  79.         it will spill off to the right.
  80.  
  81. %#d        Format an int as a signed, decimal number.  # is the
  82.         field width to use.  If the number is smaller than the
  83.         field width, it is right justified and space filled.
  84.         If # starts with a leading zero, the field is zero
  85.         filled instead of space filled.  If the number is
  86.         larger than the field width, it will spill off to the
  87.         right.
  88.  
  89. %#h        Format a long as an unsigned, hexadecimal number.  #
  90.         is the field width to use.  If the number is smaller
  91.         than the wfield width, it is right justified and space
  92.         filled. If # starts with a leading zero, the field is
  93.         zero filled instead of space filled.  If the number is
  94.         larger than the field width, it will spill off to the
  95.         right.
  96.  
  97. %#l        Format a long as a signed, decimal number.  # is the
  98.         field width to use.  If the number is smaller than the
  99.         field width, it is right justified and space filled.
  100.         If # starts with a leading zero, the field is zero
  101.         filled instead of space filled.  If the number is
  102.         larger than the field width, it will spill off to the
  103.         right.
  104.  
  105. %#o        Format an int as an unsigned, octal number.  # is the
  106.         field width to use.  If the number is smaller than the
  107.         field width, it is right justified and space filled.
  108.         If # starts with a leading zero, the field is zero
  109.         filled instead of space filled.  If the number is
  110.         larger than the field width, it will spill off to the
  111.         right.
  112.  
  113. %#u        Format an int as an unsigned, decimal number.  # is the
  114.         field width to use.  If the number is smaller than the
  115.         field width, it is right justified and space filled.
  116.         If # starts with a leading zero, the field is zero
  117.         filled instead of space filled.  If the number is
  118.         larger than the field width, it will spill off to the
  119.         right.
  120.  
  121. %#x        Format an int as an unsigned, hexadecimal number.  #
  122.         is the field width to use.  If the number is smaller
  123.         than the field width, it is right justified and space
  124.         filled. If # starts with a leading zero, the field is
  125.         zero filled instead of space filled.  If the number is
  126.         larger than the field width, it will spill off to the
  127.         right.
  128.  
  129. Strings
  130.  
  131. %#s        The argument is a pointer to a NUL-terminated array of
  132.         characters.  Copy that string to the output.  # is a
  133.         field width.  Padding is always with spaces on the right.
  134.  
  135. %c        Format an int as a character.
  136.  
  137. %#z        Output a NUL character.  # is a repeat count.
  138.  
  139. %#DEL        (Where DEL is the delete character, ^?, 127 decimal.)
  140.         Output a DEL.  # is a repeat count.
  141.  
  142. %#SP        (Where SP is the space character, 32 decimal.)  Output
  143.         a Space.  # is a repeat count.
  144.